As per my previous comment - maybe not yet in Control Center - 2nd PR?

We should remove reference to Control Center in this section.
Irrespective of the control center visibility, we do data collection, processing and deduplication

What about - Prompt data processing: Usage data is collected, processed, and deduplicated regularly. I can keep the original sentence again when the Usage data PR is available.

Or should I remove the point completely?

@JaapF @Karuna-Mendix the whole section somehow sounds very apologetic and guessing why you could have done it wrong. Documentation should be more directive IMO.

We ought to be first telling - "you are supposed to do xyz... ". These usecases when a customer might have done it wrong might be best suited for a Q&A or FAQ IMO.

What do you think?

Good point.

The recommended cross-app user identifier is the enduser's email address and the recommended place to store it is in the UserCommons.namedUserIdentifier.value.

Note that an email address is personal information and the Mendix platform therefore collects hashed values of the user identifier. If you have privacy concerns, please check the data processing agreement you have with Siemens. If you don't want to use email addresses or email addresses arenot available; you have to set a guideline on what user identifier your company will be using for cross-app user identification.

The apps in your portfolio, however, may not yet be consistently storing a cross-app user identifier value.
User metering may not have been considered when your application was originally designed. As a result, different applications may store different identifier values for the same multi-app user in the system.user.name and the UserCommons.namedUserIdentifier.value may not yet be used. Applications in your portfolio may use different user-provisioning logic. Some apps use standard identity modules (Administration, SAML, OIDC SSO, SCIM, or LDAP) while others rely on proprietary modules or app logic to create users. This can lead to inconsistent identifiers. Even when all apps use the same solution, for example, OIDC SSO, the technical identifier value for a multi-app user may still differ, see section [Avoiding pairwise identifiers]

Hi @satyammx @JaapF, I tried asking Siemens GPT to improve the current section for a more directive tone. It showed the following revision to the text. Let me know if you find it useful.

Guidelines for Unique User Identification (Deduplication)
Mendix offers multi-app user licenses, which allow a single user to access multiple applications while being counted only once for metering purposes. This applies to both internal and external users. Accurate user metering and correct multi-app user deduplication depend critically on consistent user identification across all your applications.

To ensure unique multi-app users are correctly identified and metered, you must maintain a consistent user identifier across all relevant applications.

The Mendix metering mechanism uses the UserCommons.namedUserIdentifier.value attribute as the primary user identifier. If this attribute is not available or populated, it falls back to system.user.name. For a detailed overview of relevant entities and attributes, refer to the "Domain Model Entities" section.

Key Requirements for Multi-App User Identification:

Consistent Identifier Value: The same value for a given multi-app user must be stored in the chosen identifier attribute (UserCommons.namedUserIdentifier.value or system.user.name) across all applications that user accesses. Inconsistent values will result in the user being counted as multiple distinct users.

Best Practices for Choosing and Implementing a Cross-App User Identifier:

User identification strategies can vary across application portfolios, especially if applications were developed independently or use different provisioning methods. Consider the following guidelines to establish a robust and consistent identification strategy:

1. Prioritize UserCommons.namedUserIdentifier.value: Always aim to use and populate UserCommons.namedUserIdentifier.value for user identification. This provides a dedicated field for metering purposes and offers flexibility regardless of the system.user.name value.

2. Use a Stable, Globally Unique Identifier: Select an identifier that is stable and consistently unique across your entire user base and application portfolio.

• Recommended: User's Email Address: Mendix strongly recommends storing the user's email address in UserCommons.namedUserIdentifier.value. This is typically a stable and globally unique identifier that users are familiar with.
• Handling Case Sensitivity: If using email addresses or other text-based identifiers, always store these values in lowercase to prevent metering issues due to case sensitivity. The system.user.name attribute is case-sensitive by design. Mendix's standard SAML, OIDC SSO, and SCIM modules already apply this for email claims received from Identity Providers (IdPs).

3. Address Pairwise Identifiers (e.g., OIDC sub claim): Some identity providers (like Microsoft Entra ID's OIDC sub claim) generate "pairwise" identifiers, which are unique per application for the same user. This is designed to prevent correlation across different service providers but will lead to incorrect multi-app metering within your portfolio.
   Solution for Microsoft Entra ID: If using the OIDC SSO module with Microsoft Entra ID, configure your application to store the oid claim (which contains Entra ID's user object ID) in system.user.name. The oid claim provides a consistent identifier for a multi-app user across all applications.

4. Integrating with Existing Application Logic: If your current applications use varying system.user.name values or different provisioning methods, you can implement UserCommons.namedUserIdentifier.value without altering existing logic.
   Strategy: Continue using your existing application logic for system.user.name if necessary, but additionally implement logic to populate UserCommons.namedUserIdentifier.value with your chosen consistent cross-app identifier (e.g., email address or oid claim). This ensures the metering mechanism has a reliable, consistent identifier to use.

For more information on user types and definitions, refer to the "User Types and Definitions" section.

Hi @Karuna-Mendix , yes I like the overall flow of the SiemensGPT text.
However one nuance got lost: the 'pair wise identifier' remark does not always apply.
Improved version:

"3. Address Pairwise Identifiers (e.g., OIDC sub claim): Some identity providers (like Microsoft Entra ID) generate "pairwise" identifiers (Entra ID's "sub" claim) , which are unique per application for the same user. This is designed to prevent correlation across different service providers but will lead to incorrect multi-app metering within your portfolio if you're using this technical identifier as the global unique identifier.
If using the OIDC SSO module with Microsoft Entra ID, you can use the oid claim (which contains Entra ID's user object ID) instead of "sub" as global unique identifier. The oid claim provides a consistent identifier for a multi-app user across all applications.
If you follow the above recommendation to use the user's email address as global unique identifier for user metering, pair-wise identifiers don't matter."

@JaapF Since we do not support UserCommons.Nam.... yet from a User Metering perspective, is it wise to call this out OR should we skip?

@JaapF Since we do not support UserCommons.Nam.... yet from a User Metering perspective, is it wise to call this out?

We've discussed this a couple of times and agreed that it's important to call this out to ensure the accuracy of the data.

@JaapF - this is not a supported entity from a User Metering perspective yet. Will lead to loss of usage data, if csutomers start implementing it.

How do you propose we move forward, considering supporting this additional attribute is not foreseen in the short term.

@JaapF @Karuna-Mendix
UserCommons.namedUserIdentifier.value
should we refer to this attricbute since this is not yet supported by the Metering sidecar and the metering stack overall?

as per my previous comment: "complete visibility" can be mentioned only in the 2nd PR.

Given the other page that we have written i think we can trim this down to something like:

"For accurate user metering, it is a crucial step to identify the unique multi-app user by using the same user identifier in all apps for a user. Both external and internal users can be multi-app users, so consistent identification is relevant for both."

Let's soften this here, because the metering logic is described elsewhere.
On this page it's sufficinet to say:

"For accurate user metering, External users must be explictely marked as such. If they are not, the users are counted as internal users."

Let's add:

"Userrole-based user classification is the recommended approach. It encourages and leverages application design with distinct userrole definitions for external and internal users."

Given satyam's comment about first clearly stating guidance and after that explain in more detail I think we need to start this section with clear guidance, rather than "If your apps..."

"The recommended entity attribute to store cross-app user identifiers is the UserCommons.namedUserIdentifier.value. This allows you keep the existing application logic as it is, and in addition, store the selected user identifier value for a multi-app user in this attribute. If your applications are already consistently storing the same identifier for a multi-app user in system.user.name, you don't have to use the UserCommons.namedUserIdentifier.value."

I thin k this is more positive wording.

Hi @Karuna-Mendix , yes I like the overall flow of the SiemensGPT text.
However one nuance got lost: the 'pair wise identifier' remark does not always apply.
Improved version:

"3. Address Pairwise Identifiers (e.g., OIDC sub claim): Some identity providers (like Microsoft Entra ID) generate "pairwise" identifiers (Entra ID's "sub" claim) , which are unique per application for the same user. This is designed to prevent correlation across different service providers but will lead to incorrect multi-app metering within your portfolio if you're using this technical identifier as the global unique identifier.
If using the OIDC SSO module with Microsoft Entra ID, you can use the oid claim (which contains Entra ID's user object ID) instead of "sub" as global unique identifier. The oid claim provides a consistent identifier for a multi-app user across all applications.
If you follow the above recommendation to use the user's email address as global unique identifier for user metering, pair-wise identifiers don't matter."